Skip to main content

Docusaurus + Cloudflare Pages：常見建置錯誤與手動部署流程指引

本文適用於使用 Docusaurus + Cloudflare Pages 建立靜態知識型網站的場景，目的是解決在部署過程中常見的建置失敗問題，以及教學如何使用手動部署以避免自動建置失敗。

常見錯誤與根本原因

1. Cloudflare Pages 免費版建置時常見失敗​

  • 手段與付費版相同，但有比較低優先度。
  • 會出現一些特定場景的建置錯誤，例如會因為 Node.js 相容性問題而失敗，但不是等同於服務實際不穩定。
  • 此種失敗與是否付費無關，而是與環境設定和套件相容性有關。

2. Docusaurus 中 No exports main 錯誤​

  • 錯誤例如：

    Error: Docusaurus could not load module at path "/plugins/docusaurus-plugin-minisearch/index.js"
    Cause: No "exports" main defined in /node_modules/unicorn-magic/package.json

  • 根原因：

    • Docusaurus 3.x 從 Node.js ESM 觀點出發，必須相容方式載入套件。
    • 有些老套件（如 unicorn-magic）未配置 exports 屬性，導致建置時無法正常 resolve module。

  • 解決方案：

    • 不修改套件以前措施：本地 npm run build，使 Cloudflare Pages 只會 serve build 結果，不在上面重新進行建置。

本地 build + 手動部署流程

1. 本地執行建置​

使用第三方電腦環境，執行：

npm run build

將會在屬於\u專案的 /build 目錄中產生完整的靜態網站文件。

2. 修改 Cloudflare Pages 部署設定​

項目設定值
Build command(leave blank)
Output directorybuild
  • Build Command 給空，表示 Cloudflare Pages 不再使用 npm 重新建置，而是直接上傳和部署已建好的文件。
  • Output Directory 設定為 build，確保會針對正確路徑部署。

3. 上傳 build 內容​

上傳方式可以是：

  • GitHub Commit 新的 build/
  • 或是使用手動上傳功能（如直接在網站上 upload ）

並確認：上傳的是 build/目錄內的內容（而非包含一層 build/ 目錄）。

結論

將 Docusaurus 變成靜態網站的正確流程，如需部署致 Cloudflare Pages，最安全的做法是自行 npm run build，並手動上傳。

如此可全面避免 Cloudflare Pages 自動建置漏洞，確保完全可接受。